package module.StoreService;

import common.model.Entity.StoreEntity.Category;
import network.protocol.Response;
import java.util.List;
import java.util.Optional;

/**
 * {@code CategoryService} 定义了分类（Category）相关的业务操作接口。
 * <p>
 * 主要提供以下功能：
 * <ul>
 *     <li>根据 ID 或名称查询分类</li>
 *     <li>获取分类列表（所有分类或子分类）</li>
 *     <li>创建、更新、逻辑删除分类</li>
 *     <li>统计与校验分类信息（总数、是否存在、是否有子分类等）</li>
 * </ul>
 * <p>
 * 所有方法均返回统一封装的 {@link Response} 对象，
 * 调用方可根据该对象判断操作成功与否并获取相关数据。
 */
public interface CategoryService {

    /**
     * 根据分类 ID 获取分类对象。
     *
     * @param id 分类的唯一标识
     * @return 包含分类对象的响应；
     *         如果不存在，则返回 {@link Optional#empty()}
     */
    Response<Optional<Category>> getCategoryById(long id);

    /**
     * 根据分类名称获取分类列表。
     * <p>
     * 由于分类名称可能重复，该方法可能返回多个分类。
     *
     * @param name 分类名称
     * @return 包含匹配分类的响应对象；
     *         如果不存在则返回 {@link Optional#empty()}
     */
    Response<Optional<Object>> getCategoriesByName(String name);

    /**
     * 获取系统中的所有分类。
     *
     * @return 包含分类列表的响应对象；
     *         如果没有分类，则返回空列表
     */
    Response<List<Category>> getAllCategories();

    /**
     * 根据父分类 ID 获取所有子分类。
     *
     * @param parentId 父分类的唯一标识
     * @return 包含子分类列表的响应对象；
     *         如果没有子分类，则返回空列表
     */
    Response<List<Category>> getCategoriesByParentId(long parentId);

    /**
     * 创建新的分类。
     *
     * @param category 分类实体对象，包含必要的分类信息
     * @return 操作是否成功的响应对象
     */
    Response<Boolean> createCategory(Category category);

    /**
     * 更新分类信息。
     *
     * @param category 分类实体对象，必须包含有效的 ID
     * @return 操作是否成功的响应对象
     */
    Response<Boolean> updateCategory(Category category);

    /**
     * 删除分类（逻辑删除，不会物理移除数据）。
     *
     * @param id 分类的唯一标识
     * @return 操作是否成功的响应对象
     */
    Response<Boolean> deleteCategory(long id);

    /**
     * 获取系统中分类的总数量。
     *
     * @return 包含分类总数的响应对象
     */
    Response<Long> getCategoryCount();

    /**
     * 检查指定分类 ID 是否存在。
     *
     * @param id 分类的唯一标识
     * @return 存在则返回 {@code true}，否则 {@code false}
     */
    Response<Boolean> categoryExists(long id);

    /**
     * 检查指定分类名称是否存在。
     *
     * @param name 分类名称
     * @return 存在则返回 {@code true}，否则 {@code false}
     */
    Response<Boolean> categoryNameExists(String name);

    /**
     * 检查指定父分类下是否存在子分类。
     *
     * @param parentId 父分类的唯一标识
     * @return 存在子分类则返回 {@code true}，否则 {@code false}
     */
    Response<Boolean> hasChildCategories(long parentId);
}
